В данной статье будет рассмотрена работа с шаблонами отчетов при помощи Remote API. Выполнение отчетов через SDK подразумевает последовательность обязательных действий, которые не заметны при работе в веб-интерфейсе. Для полноты картины будут приведены примеры работы с отчетами с группировкой и без группировки.
Создание отчетов
В большинстве случаев пользователи создают шаблоны отчетов в веб-интерфейсе и потом выполняют их с помощью API-запросов. Далее мы будем рассматривать именно такие случаи.
Однако создание шаблонов отчетов доступно и через SDK, для чего нужно использовать запрос report/update_report.
Последовательность действий
Для получения результатов отчетов с помощью Remote API необходимо отправить несколько запросов подряд. Использование некоторых из них зависит от наличия группировки в отчете и количества анализируемых данных. Приведем самый общий список действий:
Авторизация через запрос token/login и настройка локализации через запрос render/set_locale.
- Получение необходимых системных ID для:
элемента, для которого необходимо выполнить отчет;
- ресурса, в котором содержится шаблон отчета;
- самого шаблона отчета.
Выполнение отчета через запрос report/exec_report.
- Проверка статуса выполнения отчета через запрос report/get_report_status.
После подтверждения готовности отчета можно будет продолжать движение по инструкции. - Получение результата отчета через запрос report/apply_report_result.
Результат данного запроса предоставит количество строк, столбцов и уровней вложенности при наличии группировки. - Получение строк таблицы через запрос report/get_result_rows для отчета без группировки или через запрос report/select_result_rows для отчета с группировкой.
Выбор таблицы, уровней вложенности и отображаемых строк осуществляется на основе данных из ответа на предыдущий запрос. - Экспорт в файл через запрос report/export_result.
Данный шаг является необязательным, но достаточно несложным и полезным, поэтому мы рассмотрим и его. - Удаление результата предыдущего отчета через запрос report/cleanup_result.
Данный шаг является обязательным, если в одной сессии необходимо выполнить несколько отчетов.
Далее рассмотрим два примера работы с отчетами (без группировки и с группировкой).
Работа с отчетом без группировки
Необходимо получить результаты выполнения отчета Список поездок, доступного авторизованному по токену пользователю, для объекта Грузовик 0769 (системный ID 55555) за интервал времени с 2023 Июнь 30 20:00 до 2023 Июль 01 03:59 (GMT+0) в виде ответа на API-запрос и PDF-файла.
В веб-интерфейсе результат выглядит следующим образом:
1. Авторизация и настройка локализации
Используем запрос token/login.
https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}
Более подробно авторизация описана в одной из предыдущих статей.
Настройка локализации включает в себя установку часового пояса (она также была рассмотрена ранее), формата даты и других параметров.
Используем запрос render/set_locale.
https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"ru","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"tzOffset":134217728 | Будет применен часовой пояс GMT+0 (без перехода на летнее время). |
"language":"ru" | Будет использоваться русский язык. |
"formatDate":"%25Y.%25m.%25E%20%25H:%25M:%25S" | Будет использоваться формат даты yyyy-MM-dd и формат времени HH:mm:ss. |
2. Получение системных ID
В одной из предыдущих статей мы уже описывали, как выполнять поиск элементов по критериям, поэтому сейчас обратим внимание только на поиск ресурса и шаблона отчета.
Получим список всех ресурсов, в которых создан шаблон отчета с именем Список поездок, доступных пользователю, для которого выполнена авторизация по токену. Используем запрос core/search_items:
https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Список%20поездок","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"itemsType":"avl_resource" | Поиск будет выполнен по ресурсам. |
"propType":"propitemname" | Поиск будет выполнен по имени подэлемента. |
"propName":"reporttemplates" | Поиск будет выполнен по имени шаблона отчета. |
"propValueMask":"Список%20поездок" | В ответе будет отображен список ресурсов, в котором создан шаблон отчета с названием Список поездок. |
"sortType":"sys_name" | Сортировка будет выполнена по имени элемента. |
"force":1 | Результаты предыдущих поисков не будут учитываться. |
"flags":8193 | В ответе будет содержаться информация об основных свойствах и о созданных шаблонах отчетов. 1 + 8192 = 8193 |
"from":0;"to":0 | Ограничения по количеству найденных элементов не будут применяться. |
Обратим внимание на следующие параметры из ответа:
- nm — имя ресурса;
rep — массив шаблонов отчетов, созданных в ресурсе;
- n — имя подэлемента;
- id — системный ID.
В данном случае пользователю доступен ресурс sdk_account с системным ID 12345678, в котором находится шаблон отчета Список поездок с системным ID 1.
3. Выполнение отчета
Используем запрос report/exec_report.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":1,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"reportResourceId":12345678 | Шаблон отчета будет выбран из ресурса с системным ID 12345678. |
"reportTemplateId":1 | Будет выполнен шаблон отчета с системным ID 1. |
"reportObjectId":55555 | Отчет будет выполнен для объекта с системным ID 55555. |
"reportObjectSecId":0 | Отчет будет выполняться не для подэлемента. |
"flags":0 | Отчет будет выполнен за указанный интервал. |
"from":1688144400 | Началом интервала будет 2023 Июнь 30 20:00 (GMT+0). |
"to":1688173199 | Концом интервала будет 2023 Июль 01 03:59 (GMT+0). |
"remoteExec":1 | Отчет будет выполнен в фоновом режиме на сервере. |
4. Проверка статуса выполнения
Так как отчет выполняется в фоновом режиме на сервере, то проверим статус его выполнения, используя запрос report/get_report_status.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Код статуса 4 означает, что отчет выполнен. Интерпретацию остальных значений можно найти на странице с описанием запроса.
5. Получение результата отчета
Используем запрос report/apply_report_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Три ключевых параметра из ответа, интересующих нас, выглядят следующим образом:
- tables — показывает количество таблиц в отчете в виде массива. В данном случае упоминается только одна таблица — Поездки, следовательно, ее индекс будет равен 0.
- rows — количество строк в таблице, в данном случае их 4. Следовательно, их индексы лежат в диапазоне от 0 до 3.
- level — количество уровней вложенности, в данном случае оно равно 1, так как в отчете отсутствует группировка.
Также можно коротко перечислить другие параметры из ответа. Параметр columns говорит о количестве столбцов, далее их имена описаны в параметре header. Нулевое значение параметра msgsRendered говорит о том, что в шаблоне отчета не включено отображение сообщений на карте. Пустые параметры stats и attachments говорят о том, что в шаблоне отчета отсутствует Статистика и приложения (например, графики).
6. Получение строк таблицы
Зная индекс содержимого таблицы, отобразим ее, используя запрос report/get_result_rows.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_result_rows¶ms={"tableIndex":0,"indexFrom":0,"indexTo":3}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"tableIndex":0 | Будет отображено содержимое таблицы с индексом 0. |
"indexFrom":0 | Первая отображаемая строка будет иметь индекс 0. |
"indexTo":3 | Последняя отображаемая строка будет иметь индекс 3. |
7. Экспорт в файл
Экспортируем результат в PDF-файл, используя запрос report/export_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Список%20поездок"}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"format":2 | Результат отчета будет экспортирован в формат PDF. |
"compress":0 | Экспортируемый файл не будет сжат (добавлен в архив). |
"outputFileName":"Список%20поездок" | Экспортируемый файл будет иметь имя Список поездок. |
Ответ на данный API-запрос не отображается, вместо этого автоматически начинается загрузка файла.
8. Удаление результата предыдущего отчета
Используем запрос report/cleanup_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Нулевое значение означает успешное удаление.
Работа с отчетом с группировкой
Необходимо получить результаты выполнения отчета Поездки с группировкой, доступного авторизованному по токену пользователю, для объекта Грузовик 0769 (системный ID 55555) за интервал времени с 2023 Июнь 30 20:00 до 2023 Июль 01 03:59 (GMT+0) в виде ответа на API-запрос и PDF-файла.
В веб-интерфейсе результат выглядит следующим образом:
По результату выполнения в веб-интерфейсе видно, что таблица Поездки имеет группировку по месяцам и дате, то есть отчет имеет 3 уровня вложенности:
- на 1-м уровне расположены строки с месяцами;
- на 2-м — строки с датой в рамках месяца;
- на 3-м — строки непосредственно с поездками в рамках даты.
1. Авторизация и настройка локализации
Используем запрос token/login.
https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"ЗНАЧЕНИЕ_ТОКЕНА"}
Более подробно авторизация описана в одной из предыдущих статей.
Настройка локализации включает в себя установку часового пояса (она также была рассмотрена ранее), формата даты и других параметров.
Используем запрос render/set_locale.
https://hst-api.wialon.com/wialon/ajax.html?svc=render/set_locale¶ms={"tzOffset":134217728,"language":"ru","formatDate":"%25E.%25m.%25Y%20%25H:%25M:%25S"}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"tzOffset":134217728 | Будет применен часовой пояс GMT+0 (без перехода на летнее время). |
"language":"ru" | Будет использоваться русский язык. |
"formatDate":"%25Y.%25m.%25E%20%25H:%25M:%25S" | Будет использоваться формат даты yyyy-MM-dd и формат времени HH:mm:ss. |
2. Получение системных ID
В одной из предыдущих статей мы уже описывали, как выполнять поиск элементов по критериям, поэтому сейчас обратим внимание только на поиск ресурса и шаблона отчета.
Получим список всех ресурсов, в которых создан шаблон отчета с именем Поездки с группировкой, доступных пользователю, для которого выполнена авторизация по токену. Используем запрос core/search_items:
https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_resource","propType":"propitemname","propName":"reporttemplates","propValueMask":"Поездки%20с%20группировкой","sortType":"sys_name"},"force":1,"flags":8193,"from":0,"to":0}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"itemsType":"avl_resource" | Поиск будет выполнен по ресурсам. |
"propType":"propitemname" | Поиск будет выполнен по имени подэлемента. |
"propName":"reporttemplates" | Поиск будет выполнен по имени шаблона отчета. |
"propValueMask":"Поездки%20с%20группировкой" | В ответе будет отображен список ресурсов, в котором создан шаблон отчета с названием Поездки с группировкой. |
"sortType":"sys_name" | Сортировка будет выполнена по имени элемента. |
"force":1 | Результаты предыдущих поисков не будут учитываться. |
"flags":8193 | В ответе будет содержаться информация об основных свойствах и о созданных шаблонах отчетов. 1 + 8192 = 8193 |
"from":0;"to":0 | Ограничения по количеству найденных элементов не будут применяться. |
Обратим внимание на следующие параметры из ответа:
- nm — имя ресурса;
rep — массив шаблонов отчетов, созданных в ресурсе;
- n — имя подэлемента;
- id — системный ID.
В данном случае пользователю доступен ресурс sdk_account с системным ID 12345678, в котором находится шаблон отчета Поездки с группировкой с системным ID 2.
3. Выполнение отчета
Используем запрос report/exec_report.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/exec_report¶ms={"reportResourceId":12345678,"reportTemplateId":2,"reportObjectId":55555,"reportObjectSecId":0,"interval":{"flags":0,"from":1688144400,"to":1688173199},"remoteExec":1}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"reportResourceId":12345678 | Шаблон отчета будет выбран из ресурса с системным ID 12345678. |
"reportTemplateId":2 | Будет выполнен шаблон отчета с системным ID 2. |
"reportObjectId":55555 | Отчет будет выполнен для объекта с системным ID 55555. |
"reportObjectSecId":0 | Отчет будет выполняться не для подэлемента. |
"flags":0 | Отчет будет выполнен за указанный интервал. |
"from":1688144400 | Началом интервала будет 2023 Июнь 30 20:00 (GMT+0). |
"to":1688173199 | Концом интервала будет 2023 Июль 01 03:59 (GMT+0). |
"remoteExec":1 | Отчет будет выполнен в фоновом режиме на сервере. |
4. Проверка статуса выполнения
Так как отчет выполняется в фоновом режиме на сервере, то проверим статус его выполнения, используя запрос report/get_report_status.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/get_report_status¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Код статуса 4 означает, что отчет выполнен. Интерпретацию остальных значений можно найти на странице с описанием запроса.
5. Получение результата отчета
Используем запрос report/apply_report_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/apply_report_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Три ключевых параметра из ответа, интересующих нас, выглядят следующим образом:
- tables — показывает количество таблиц в отчете в виде массива. В данном случае упоминается только одна таблица — Поездки, следовательно, ее индекс будет равен 0.
- rows — количество строк в таблице, в данном случае их 2. Следовательно, их индексы лежат в диапазоне от 0 до 1. Речь идет только про строки на верхнем уровне вложенности, внутри их может быть больше.
- level — количество уровней вложенности, в данном случае оно равно 3, так как в отчете присутствует группировка. Следовательно, в таблице существуют уровни с индексами от 0 до 2.
Также можно коротко перечислить другие параметры из ответа. Параметр columns говорит о количестве столбцов, далее их имена описаны в параметре header. Нулевое значение параметра msgsRendered говорит о том, что в шаблоне отчета не включено отображение сообщений на карте. Пустые параметры stats и attachments говорят о том, что в шаблоне отчета отсутствует Статистика и приложения (например, графики).
6. Выбор строк в многоуровневой таблице
Зная индекс содержимого таблицы отобразим ее, используя запрос report/select_result_rows.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/select_result_rows¶ms={"tableIndex":0,"config":{"type":"range","data":{"from":0,"to":1,"level":2}}}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"tableIndex":0 | Будет отображено содержимое таблицы с индексом 0. |
"type":"range" | Запрашиваться будет последовательность строк. |
"from":0 | Первая отображаемая строка будет иметь индекс 0. |
"to":1 | Последняя отображаемая строка будет иметь индекс 1. |
"level":2 | Результат будет отображать уровни вложенности вплоть до индекса 2. |
7. Экспорт в файл
Экспортируем результат в PDF-файл, используя запрос report/export_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result¶ms={"format":2,"compress":0,"outputFileName":"Поездки%20с%20группировкой"}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Параметр и его значение | Описание |
---|---|
"format":2 | Результат отчета будет экспортирован в формат PDF. |
"compress":0 | Экспортируемый файл не будет сжат (добавлен в архив). |
"outputFileName":"Поездки%20с%20группировкой" | Экспортируемый файл будет иметь имя Поездки с группировкой. |
Ответ на данный API-запрос не отображается, вместо этого автоматически начинается загрузка файла.
8. Удаление результата предыдущего отчета
Используем запрос report/cleanup_result.
https://hst-api.wialon.com/wialon/ajax.html?svc=report/cleanup_result¶ms={}&sid=ИДЕНТИФИКАТОР_СЕССИИ
Нулевое значение означает успешное удаление.
Особенности получения результатов
Получение данных из таблиц может осуществляться с помощью запросов report/get_result_rows или report/select_result_rows, в которых используется параметр tableIndex, чтобы обратиться к таблице с определенным индексом. При этом необходимо учитывать, что при выполнении отчета за разные интервалы индекс одной и той же таблицы может меняться из-за наличия или отсутствия других таблиц.
Для лучшего понимания ситуации рассмотрим пример. Предположим, что в шаблон отчета добавлены таблицы Поездки, Сливы и Геозоны. При выполнении отчета за интервал с 1 по 3 июля результат будет содержать все таблицы, а потому их индексы примут следующие значения:
0 — Поездки
1 — Сливы
2 — Геозоны
А при выполнении отчета за интервал с 4 по 6 июля индексы некоторых таблиц поменяются из-за отсутствия зарегистрированных сливов и примут другие значения:
0 — Поездки
1 — Геозоны
В данном примере хорошо видно, что при выполнении отчета за разные интервалы индекс таблицы Геозоны изменяется. Следовательно, обращение к таблице с индексом 2 не всегда будет выводить информацию о посещении геозон. Для исправления подобных ситуаций рекомендуется применять дополнительные проверки, например, по названию таблицы или ее столбцов.